Night Owl 6/Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso/018a/macade.zip/MCOMPILE.DOC

Text File | 1991-12-07 | 14KB | 296 lines

                           MCompile.exe
              A Utility for Compiling ASCII Text File
                Listings of WordPerfect 5.1 Macros
                into Executable Macro (.wpm) Files

                                by

                      Jeffrey S. Kane, Ph.D.
                Performance Sciences International
                          Summerfield, NC

1.   Read the REGISTER.doc, LICENSE.doc, and WARRANTY.doc files distributed
     with this macro.

2.   Requires:

     A.   WordPerfect 5.1 (for use of compiled macros)

     B.   MS/PC-DOS 3.0 or higher

     C.   An ASCII source file that conforms to the compiler's
          structure and syntax specifications.

3.   Features:

     A.   Fast    (e.g., less than 4 seconds for a 10K source file
          on 386DX-20 machine).


     B.   Compact .exe file size (<10.8 KBytes)

     C.   Accurate

     D.   Powerful: accepts source files of unlimited size.

     E.   Handles either spaces or tabs as formatting characters
          at the beginnings of lines (up to first significant
          character on any line).

     F.   Case insensitive: accepts commands in whatever case you
          feel like entering them.

4.   Installation:

     No installation is required other than to copy the
     MCompile.exe file to the directory where your WordPerfect
     macros reside.  As in the case of Macrolst, we recommend
     locating MCompile in this directory at least for the sake of
     convenience, and of necessity if you plan to use the EditM
     or EditWP system for editing macros.

5.   Operation:

     A.   Structure of Source Files

               ASCII text file listings of macros, which we'll
          refer to as source files from this point onward, must
          conform to an easily achieved structure in order to be
          successfully compiled.  The structure of a source file
          consists of three separate components, as follows:

          1)   Header:  all characters from the start of the file
           to the 'STARTMACRO:' code delimiter.
          2)   Code Delimiter:  the word 'STARTMACRO:', including
               its terminating colon.
          3)   Source Code:  all characters from the end of the
               code delimiter to the end of the file.

               The compiler will first search through the Header to
          find the phrase,

              Macro Description:

      All the characters up to a maximum of 39 that occur between
      the colon at the end of the above phrase and the first end of
      line sequence (ASCII 13ASCII 10, produced by pressing your
      [ENTER] key) encountered before the beginning of the
      'STARTMACRO:' code delimiter will be used as the macro
      description.    Thus, if you intend there to be no description
      for the macro, either leave out the 'Macro Description:'
      phrase altogether, or follow it with an immediate press of
      your [ENTER] key.

               The compiler then looks for the 'STARTMACRO:' code
          delimiter.  This delimiter MUST appear before the start
          of the source code, or no compilation will occur.  Every
          character after the code delimiter to the end of the
          source file will be compiled into macro code.

               To generate an example of how the structure of a
          source file should look, use the Macrolst program to
          create a source file from one of your existing macros.
          Macrolst creates files which are directly recompilable
          back to macros (i.e., .wpm files).

     B.   Syntax of Source Files

      1)   All macro and keystroke commands must begin with an
           opening French brace ({) and end with a closing
           French brace (}).

      2)   In earlier versions of MacroAde the MCompile program
           required that the case (i.e., upper or lower) of every
           letter between the braces in all macro and keystroke
           commands exactly match that used in the display format
           of the commands.  However, several macro enthusiasts
           have suggested that the goal of any external editing
           capability is ease of use.  To have to observe the
           proper case of command characters conflicts with that
           goal.  Consequently, in this version any mix of cases
           may be used in entering any command.  However, MacroLst
           will continue to translate the commands in a macro in
           accordance with WordPerfect's case format conventions.
           in WordPerfect.

      3)   Most of the macro commands are listed and explained in
           detail in Appendix K of the WordPerfect 5.1 manual.
           The complete list of the commands is presentedd for
           syntax reference purposes in the COMMANDS.ref file
           contained in the MacroAde package.

      4)   WordPerfect furnishes no list of the keystroke commands
           in the form in which they actually appear in WordPerfect's
           macro editor.  MacroAde provides the needed list of these
           commands in their correct form in its COMMANDS.ref file,
           following the list of macro commands.  Next to each
           keystroke command its WordPerfect code is listed,
           which is needed for some macro commands.  These
           commands must be entered exactly as they appear in
           this list EXCEPT for their case or a syntax error will
           occur and halt compilation.

      5)   One special syntax rule that is unique to creating
               source files compilable by MCompile concerns the
               manner in which non-keyboard characters are entered
               to correspond to the use of WordPerfect's 'Compose'
               feature.  This feature is used to access characters
               in WordPerfect character sets above Set 0 (i.e.,
               Sets 1-12), although it can also be used for Set 0
           if there is some reason to do so (e.g., see below for
           the special case of specifying braces as literal
           characters, not parts of commands).  You can specify
               any of these characters in the 13 Character Sets
               (see Appendix P of WordPerfect manual) by entering
           its code using the following syntax:

                    [:S,C]
               where:

                     S =  the WordPerfect Character Set number (0-
                          12)
                     C =  the number of the character within the
                          specified Character Set
               For example, to specify the copyright symbol, which
               is character 23 in set 4, you could enter:

                    [:4,23]

           NOTE: Even though the compiler accepts certain high
           ASCII codes in the above form (e.g., [:0,250]) for
           various purposes in the construction of .wpm files,
           do not use any other high ASCII characters (i.e., >126)
           in your macro if they aren't specifically allowed in
           these instructions.  WordPerfect's character set 0 only
           contains the first 126 ASCII characters; use of others
           not authorized here will not be recognized in WordPerfect.

          6)   The easiest approach to handling spaces and tabs in the
               compilation process would be to merely interpret them
               directly.  However, this approach would make it very
               difficult to use editors which expand all tabs into spaces.
               One of the most widely used editors--QEDIT--offers a choice
               of either the latter sort of tab expansion or a literal
               treatment of tabs which displays the tab character but
               doesn't execute it.  The result of the latter approach is
               a very unreadable display since none of the indentation
               actually appears.  The tab expansion option produces a
               readable display but eliminates all the tabs, which would
               leave the compiled macro without any indentation formatting.
               This can be slightly alleviated by using QEDIT's Tabs Out
               configuration option, but that only applies to new lines
               inserted in a macro and only deals with space sequences of
               one fixed length.  A similar problem arises in using the
               EDITWP macro to edit macros as WordPerfect documents.  This
               macro saves the documents via WordPerfect's Text Out feature,
               which converts all tabs to spaces, thereby eliminating all
               indentation formatting information if the compiler were
               designed to interpret all spaces literally.  Clearly, an
               approach other than literal interpretation of tabs and
               spaces is needed.

               MCompile intelligently parses all instances of the space
               character into either tabs or literal spaces.  This enables
               MacroLst to produce source files using the expansion of tabs
               to spaces (ASCII 32) that are highly readable in any editor.
               MCompile will then convert all sequences of 3 or 4 spaces
               back to tabs.

               The cost of this approach is that with one exception, all
               spaces intended to be retained as literal spaces within
               the macro must be represented by the ASCII 250 character
               or by the [:0,250] character code (if your editor won't
               represent ASCII 250).  The exception is any space that occurs
               between two characters that are neither space (i.e., ASCII 32)
               nor tab (i.e., ASCII 9) characters, and that doesn't occur at
               the very start of a line, as in a space that separates two
               words in a comment.  These singly-occurring spaces will be
               compiled as literal spaces in the macro.

               Many editors offer a keyboard macro capability that will
               make the use of ASCII 250 much easier.  For example, in
               QEDIT you can simply edit your keyboard configuration file
               (QCONFIG.DAT is its default name if you haven't renamed it)
               and assign the following line to any key that you want to
               use for ASCII 250:

                                macro_begin '·'

               The character between the single quotes is ASCII 250, which
               you can access in QEDIT by holding down the ALT key and
               typing 250 on the numeric keypad (actually, on my keyboard
               I have to hold down both CTRL and ALT).  Once you've changed
               the keyboard configuration file, you'll then have to run
               the QCONFIG.EXE program, select the Keys option, and then save
               the setup in order for the new key assignment to take effect.

          7)   If you need to continue a line containing a sequence of
               literal spaces (i.e., spaces that actually need to be in
               the macro) in such a manner that would cause one of the
               literal spaces to start the next line, and for some reason
               you cannot use the ASCII 250 character (e.g., your editor
               won't allow you access to it), then represent it and all
               other such literal spaces with the [:0,250] character code.

          8)   If your editor converts tabs to spaces (e.g., QEDIT does
               this in its most common configuration of Tab Expansion ON),
               make sure that the physical tabs are set at 4 spaces.  If
               they are set at higher or lower values, you'll end up larger
               or smaller indentations than you expected.

          9)   Do NOT use the "{" and "}" characters in any way other
           than to enclose a macro or keystroke command within the
           macro source code.  The compiler assumes that all
           occurrences of these characters are meant to enclose
           commands and will generate an error and terminate
           compilation if they occur without enclosing commands.
           This is the only difference from WordPerfect's internal
           macro editor, which allows you to use these French braces
           as characters having nothing to do with commands.
           You can, however, enter non-command related braces
           in character code form.    Specifically, you can insert
           literal braces anywhere in a macro by using the following
           codes:
                 "{" = [:0,123]
                 "}" = [:0,125]

         10)   A violation of any of these syntax rules or the
               occurrence of an illegal or misspelled command will
               cause MCompile to issue an error message and halt
               execution.  It also assigns a value from 11 to 17
               to the DOS Errorlevel variable to designate the
               occurrence of a particular error.  Checking
               Errorlevel is a useful way of checking the
               compilation process when MCompile is executed
               within a batch file.

     C.   Once a source file is ready for compiling, the actual
          compilation process is invoked by the following command:

              MCompile macro(.lst)

      Note that the name of the source file on the MCompile
          command line may exclude the .lst extension, but will
          accept the name with this extension if it is given.
          MCompile assumes that any source file has the .lst
          extension, but this assumption may be overridden by
          explicitly specifying a different extension.

     D.   If for some reason the compilation fails and a macro of
          that name previously existed, the prior version of the
          macro will be preserved.

6.   Technical support:

     Free technical support will be furnished to any licensed user
     who calls on weekdays during the hours from 9:00 a.m. to 5:00 p.m.
     (Eastern) at the following number:  [phone]

     We may also be reached by mail at:

     Performance Sciences International
     Suite 1250
     3001 Latta Drive
     Summerfield, NC  27358